feat(autoware_carla_interface): publish CARLA traffic-light states, matched to the map by position - #13327

…atched to the map by position

Bridge the CARLA server's traffic-light states into Autoware's perception
output so a CARLA closed loop can run without camera-based recognition.

The key problem is associating a CARLA traffic light with an Autoware
`traffic_light_group_id` (a `traffic_light` regulatory-element id in the
lanelet2 map). Instead of assuming the CARLA OpenDRIVE signal id equals the
regulatory-element id (true only for maps auto-generated from the same
OpenDRIVE) or hand-writing an id table, the bridge discovers the mapping
geometrically: each CARLA light head is matched to the nearest lanelet2 light
head and its state is published under every regulatory element that references
that head. This works for hand-authored / Vector Map Builder maps too.

- New `modules/traffic_light_matcher.py`: parses the lanelet2 `.osm` directly
  (reads `local_x`/`local_y`, i.e. the map frame; no lanelet2/projector
  dependency), keys physical heads by their `refers` way, and matches CARLA
  heads conservatively (distance threshold + a disjoint-group ambiguity ratio),
  dropping and logging ambiguous / too-far lights rather than guessing.
- `carla_ros.py`: publishes `TrafficLightGroupArray` on
  /perception/traffic_light_recognition/traffic_signals, aggregated per group.
- `carla_autoware.py`: `force_green` freezes all lights green for camera-less
  runs.
- Parameters grouped under the `traffic_light.` namespace; resolution order is
  id-map override -> position match -> OpenDRIVE-id fallback.
- Unit tests for the matcher; README documents the feature.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Masaya Kataoka <cld-masaya.kataoka@tier4.jp>

…cene

Address the second review round:

- traffic_light.id_map now accepts several group ids per OpenDRIVE signal id,
  formatted `opendrive_id:group_id[|group_id...],...` (repeated keys merge). A
  physical head shared by multiple regulatory elements can therefore be pinned
  to all of them via one override, matching the position matcher's shared-head
  behaviour, instead of only ever recovering a single group. (Codex P2)
- Reduce complexity flagged by the CodeScene gate by extracting helpers so the
  hot methods stay flat and short:
  - traffic_light_matcher: split `load_map_traffic_lights` into node/way/relation
    parsers (Complex Method / Bumpy Road) and pull the per-head decision out of
    `match_traffic_lights` into `_classify_head` (Large Method).
  - carla_ros: split `_resolve_traffic_light_groups` into `_apply_id_map_override`
    / `_match_actors_to_map` / `_fallback_opendrive_groups`; the override parser
    is now the pure, unit-tested `parse_id_map_override`.
  - carla_autoware: fold the enable check into `_force_green_traffic_lights` so
    `load_world` keeps a single unconditional call and gains no branch.
- Extend unit tests for the multi-id override parsing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Masaya Kataoka <cld-masaya.kataoka@tier4.jp>

Follow-up to the previous refactor, targeting the two rules still flagged on the
traffic-light matcher:

- Extract `_add_relation_heads` so `load_map_traffic_lights` is a single flat loop
  with no nested conditional block (clears Bumpy Road Ahead).
- Pass the per-run matching state as one `_MatchContext` namedtuple instead of a
  seven-parameter list, so `_classify_head(head, ctx)` takes two arguments (clears
  Excess Number of Function Arguments).

No behavioural change; tests still pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Masaya Kataoka <cld-masaya.kataoka@tier4.jp>

… the off state

Review follow-ups on the CARLA traffic-light bridge:

- traffic_light.id_map no longer lets a typo through split()/int(). A
  malformed entry ("12" with no ':', "12:" with no group id, or a
  non-integer id) is skipped with a warning naming the offending entry
  instead of raising on the first simulation tick or silently overriding
  a light with an empty group list; the other entries still apply.
  Reporting goes through an optional on_invalid callback so the parser
  stays ROS-free and unit-testable.

- The ambiguity guard now rejects an exact tie. With two heads of
  different signals at the same point both distances are 0, so
  "nearest > ratio * second" degenerates to 0 > 0 and the winner came
  down to the order the ways appear in the .osm; a tie has no winner and
  is now reported like any other ambiguous match.

- CARLA's TrafficLightState.Off is a known state (the signal is dark),
  but it was published as an UNKNOWN-color lamp with status SOLID_ON,
  i.e. "unknown color, lit". It now maps to status SOLID_OFF, and only a
  state the bridge cannot interpret stays UNKNOWN/UNKNOWN.

Tests cover the malformed-entry cases and the coincident-head tie.

Signed-off-by: Masaya Kataoka <ms.kataoka@gmail.com>

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCAQHBrcSCmJoKn5Xi7s3k

…pell check

"unsignalized" is not in the Autoware spell-check dictionary and failed
spell-check-differential. Say the same thing in words the dictionary
knows; no behavior change.

Signed-off-by: Masaya Kataoka <ms.kataoka@gmail.com>

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCAQHBrcSCmJoKn5Xi7s3k

…uity test

CodeScene flagged the previous commit for a Complex Method
(_parse_id_map_entry: two try/except blocks and a loop in one function)
and a Complex Conditional (_classify_head's compound ambiguity check).

Pull the pieces out instead of suppressing them: _parse_id (one integer
id) and _parse_id_map_groups (the group-id list) leave the entry parser
as a separator check plus two calls, and _is_ambiguous names the
runner-up test as a guarded sequence of single conditions. No behavior
change; the matcher tests still pass.

Signed-off-by: Masaya Kataoka <ms.kataoka@gmail.com>

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCAQHBrcSCmJoKn5Xi7s3k